Serialize and restore compiled schema by Ahmedmhmud · Pull Request #115 · hyperjump-io/json-schema

Ahmedmhmud · 2026-04-25T18:04:01Z

This PR adds experimental helpers to serialize and deserialize compiledSchema so applications can persist and restore compiled validation logic more easily. It handles the non-JSON parts of a compiled schema by preserving RegExp values and restoring EvaluationPlugins by ID, first from built-in plugins and then from an optional pluginsById map for custom plugins, with a clear error when a plugin cannot be found. It also wires the helpers into the experimental API surface and includes focused tests and error cases.

…hema

jdesrosiers

I think using replacer/reviver for plugins isn't the best approach. The pattern matching approach used by isPlugin feels clunky. Since those plugins are always in a known location, I think it makes more sense to convert them before serialization.

Converting RegEpx is different because they could be anywhere and determining if something is a RegExp is trivial.

Plugins isn't actually a Set, it's an array. That was a error in the type that has already been corrected. Rebase your branch to get the correct type.

The exported functions should be a the top of the file with helper functions below.

Using __type isn't going to work. If someone uses that as a property name in their schema, this approach could break. You'll need to pick a key that won't collide with anything that could end up in a schema. I suggest a UUID. That way it's effectively impossible for a user to accidentally create a schema with a conflict.

Ahmedmhmud · 2026-04-30T22:43:40Z

Converted plugin objects in plugins to UUID-marked references before serialization to avoid shape-matching and property collisions. RegExp values are serialized and revived using a UUID marker. Deserializer accepts both the new UUID markers and legacy __type markers for compatibility. Updated also tests in compiled-schema-serialization.spec.ts.

jdesrosiers · 2026-05-01T18:49:37Z

+const REGEXP_MARKER = "a6d8f3e1-9b2c-4f7a-8d5b-1c2e3f4a5b6c";
+
+export const serialize = (compiledSchema) => {
+  const ast = compiledSchema?.ast ? { ...compiledSchema.ast } : undefined;


ast isn't optional on compiledSchema.

jdesrosiers · 2026-05-01T18:52:24Z

+  if (ast && (Array.isArray(ast.plugins) || ast.plugins instanceof Set)) {
+    ast.plugins = [...ast.plugins].map((plugin) => {


ast.plugins will never be a Set.

jdesrosiers · 2026-05-01T18:54:29Z

+      if (!plugin?.id) {
+        throw Error("Cannot serialize plugin without id");
+      }
+      return { [PLUGIN_MARKER]: true, id: plugin.id };


The PLUGIN_MARKER isn't necessary because we're not using replacer/reviver for this part. You should be able to just replace the plugin with its id.

jdesrosiers · 2026-05-01T19:01:22Z

+    // Legacy support: old tests/serializations used a __type marker.
+    if (value.__type === "RegExp") {
+      return new RegExp(value.source, value.flags);
+    }


__type was introduced in this PR. No one is depending on it. This looks like a mistake an AI coding tool would make. If you use those tools make sure you check everything they do and make sure it makes sense.

jdesrosiers · 2026-05-01T19:03:08Z

+    if (value[PLUGIN_MARKER]) {
+      return resolvePlugin(value.id, options);
+    }


Don't restore plugins in the reviver. Do it as a separate step like in serialize.

jdesrosiers · 2026-05-01T19:03:34Z

+    if (value.__type === "Plugin") {
+      return resolvePlugin(value.id, options);
+    }
+
+    if (value.__type === "PluginSet") {
+      // Legacy PluginSet: restore to an array of plugin objects
+      return (value.values || []).map((p) => resolvePlugin(p.id, options));
+    }


Unnecessary

Ahmedmhmud · 2026-05-02T22:09:51Z

Thanks for heads up, I will update it.

Ahmedmhmud · 2026-05-06T15:15:29Z

Hi, @jdesrosiers
I have a question about plugins
You said earlier that plugins aren't set, they are an array
But compile() still produces plugins as Set() in lib/core.js and also in lib/validation.js treats plugins as a set, so what do you suggest?
Do I check if it is as a set like I was doing?
or I can open a new PR to fix it and all the code that depends on plugins as a set or creating plugins as a set?

BTW, I finished the work on this PR by treating plugins as an array, I can make tests pass by just checking ast.plugins instanceof Set and change it with the rest of conversion process in the other PR

jdesrosiers · 2026-05-06T17:15:53Z

Sorry! I was confusing the plugins in AST with plugins in ValidationContext. You're right, it is a Set in the AST. It's a Set because those are keyword-specific plugins that only get added if the keyword is present in the schema and they should only get added once if the keyword is used multiple times.

So, you should expect a Set, serialize to an array, and restore the array as a Set. An please also fix the type declaration.

Ahmedmhmud · 2026-05-07T19:28:21Z

No problem at all, I fixed the old part and also the type declaration.

jdesrosiers · 2026-05-08T17:15:46Z

+  const ast = compiledSchema.ast ? { ...compiledSchema.ast } : undefined;
+  if (ast && ast.plugins instanceof Set) {


ast is always present and is always a Set. These checks are unnecessary.

jdesrosiers · 2026-05-08T17:23:35Z

+export const serialize = (compiledSchema) => {
+  const ast = compiledSchema.ast ? { ...compiledSchema.ast } : undefined;
+  if (ast && ast.plugins instanceof Set) {
+    ast.plugins = [...ast.plugins].map((plugin) => {


This pattern isn't great because it creates an intermediate array that isn't necessary. You can use @hyperjump/pact's map function that works on any iterable instead of just on functions (Pact.map((plugin) => ..., ast.plugins). Or, just use a normal for loop to build the array.

jdesrosiers · 2026-05-08T17:24:38Z

+  const ast = compiledSchema.ast ? { ...compiledSchema.ast } : undefined;
+  if (ast && ast.plugins instanceof Set) {
+    ast.plugins = [...ast.plugins].map((plugin) => {
+      if (!plugin?.id) {


plugin should never be undefined. The ? is unnecessary.

jdesrosiers · 2026-05-08T17:25:14Z

+      if (!plugin?.id) {
+        throw Error("Cannot serialize plugin without id");
+      }
+      return { id: plugin.id };


There's no need for this to be an object. return plugin.id should be sufficient.

jdesrosiers · 2026-05-08T17:43:49Z

+
+  return JSON.stringify(toSerialize, (_key, value) => {
+    if (value instanceof RegExp) {
+      return { [REGEXP_MARKER]: true, source: value.source, flags: value.flags };


If we slightly change the way this is represented, we can simplify the deserialize reviver function.

Suggested change

return { [REGEXP_MARKER]: true, source: value.source, flags: value.flags };

return { [REGEXP_MARKER]: { source: value.source, flags: value.flags } };

jdesrosiers · 2026-05-08T17:44:58Z

+    if (!value || typeof value !== "object") {
+      return value;
+    }
+
+    if (value[REGEXP_MARKER]) {
+      return new RegExp(value.source, value.flags);
+    }


With the previous suggested change, this can simply be ...

Suggested change

if (!value || typeof value !== "object") {

return value;

}

if (value[REGEXP_MARKER]) {

return new RegExp(value.source, value.flags);

}

if (key === REGEXP_MARKER) {

return new RegExp(value.source, value.flags);

}

jdesrosiers · 2026-05-08T17:46:02Z

+    return value;
+  });
+
+  if (Array.isArray(parsed?.ast?.plugins)) {


This is unnecessary. plugins will always be present and always be an array.

jdesrosiers · 2026-05-08T18:00:36Z

+  });
+
+  if (Array.isArray(parsed?.ast?.plugins)) {
+    parsed.ast.plugins = new Set(parsed.ast.plugins.map((plugin) => resolvePlugin(plugin.id, options)));


We can avoid the intermediate array with @hyperjump/pact.

Suggested change

parsed.ast.plugins = new Set(parsed.ast.plugins.map((plugin) => resolvePlugin(plugin.id, options)));

parsed.ast.plugins = Pact.pipe(

parsed.ast.plugins,

Pact.map((pluginUri) => resolvePlugin(pluginUri, options))

Pact.collectSet

);

jdesrosiers · 2026-05-08T18:03:04Z

+};
+
+const resolveBuiltInPlugin = (pluginId) => {
+  if (typeof pluginId !== "string" || !pluginId.endsWith("#plugin")) {


pluginId would never not be a string.

Ahmedmhmud added 3 commits April 25, 2026 15:59

adding serialization module for serializing and restoring compiled sc…

bfe0b87

…hema

wiring compiled schema serialization helpers with experimental API

7c3b313

adding testing module for serialization

18c4e27

jdesrosiers requested changes Apr 27, 2026

View reviewed changes

Ahmedmhmud added 2 commits May 1, 2026 01:31

using UUID markers and pre-convert plugins

1ba4c26

treating plugins as an array

3a6ef62

jdesrosiers requested changes May 1, 2026

View reviewed changes

Ahmedmhmud added 2 commits May 7, 2026 22:24

restore ast.plugins as Set after deserialization

e60d99a

making type declaration of ast.plugins as Set

54ac811

jdesrosiers requested changes May 8, 2026

View reviewed changes

srivastava-diya mentioned this pull request May 9, 2026

Make validator serialization a first-class feature #112

Open

		if (ast && (Array.isArray(ast.plugins) \|\| ast.plugins instanceof Set)) {
		ast.plugins = [...ast.plugins].map((plugin) => {

		const ast = compiledSchema.ast ? { ...compiledSchema.ast } : undefined;
		if (ast && ast.plugins instanceof Set) {

	return { [REGEXP_MARKER]: true, source: value.source, flags: value.flags };
	return { [REGEXP_MARKER]: { source: value.source, flags: value.flags } };

-    parsed.ast.plugins = new Set(parsed.ast.plugins.map((plugin) => resolvePlugin(plugin.id, options)));
+    parsed.ast.plugins = Pact.pipe(
+      parsed.ast.plugins,
+      Pact.map((pluginUri) => resolvePlugin(pluginUri, options))
+      Pact.collectSet
+    );

Uh oh!

Conversation

Ahmedmhmud commented Apr 25, 2026

Uh oh!

jdesrosiers left a comment

Choose a reason for hiding this comment

Uh oh!

Ahmedmhmud commented Apr 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ahmedmhmud commented May 2, 2026

Uh oh!

Ahmedmhmud commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdesrosiers commented May 6, 2026

Uh oh!

Ahmedmhmud commented May 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Ahmedmhmud commented May 6, 2026 •

edited

Loading